home *** CD-ROM | disk | FTP | other *** search
/ ShareWare OnLine 2 / ShareWare OnLine Volume 2 (CMS Software)(1993).iso / database / msgobj10.zip / PIPBASE.DOC < prev    next >
Text File  |  1993-03-26  |  14KB  |  322 lines
  1. Hello, World!
  2.  
  3. Once upon a time, my cosysop Elio Fenoglio told me: "Idea *:-) Why don't we
  4. create a new standard for message base, that minimizes the space occupied on 
  5. disks by storing messages in a compressed form, and that eliminates all 
  6. limits of the Hudson QuickBase?". My first answer was: "No, it's too 
  7. difficult! and I cannot impose a new standard."
  8.  
  9. In the meantime, I was improving AtomAnt, a message reader for the Cambridge 
  10. Computer Z88 that reads messages directly from a .pkt (there's no space for 
  11. tossing, in its 160 K of static RAM). To maximize the amount of messages I 
  12. could read when I was travelling by train, I though "Why don't read messages 
  13. directly from a compressed .MO0? using a simpler packer than ARC, it's not a
  14. hard work." After some days, I created Z88PIP, a message packer for PC IBM, 
  15. and AtomAnt 1.02, the first reader that reads messages directly from a 
  16. compressed packet. Happy for this, I gone to bed.
  17.  
  18. It was about 2:00AM, when I woke up with the enlightment: "BUT I REALIZED IT: 
  19. A COMPRESSED MESSAGE BASE!". After some all-nighters, I projected the PipBase 
  20. message format, and I started to develop all necessary programs: an editor, a 
  21. mail processor, and some utilities to do maintenance.
  22.  
  23. Thanks to Elio Fenoglio (my cosysop and author of PipSetup), Giovanni Lopes 
  24. Pegna (author of Mercurio), Marco Maccaferri (author of Lora), Marco Russo 
  25. (author of some interesting libraries) and Stefano Pasquini (the first who
  26. forwarded my PipBase out of Italy), the idea spread around the world.
  27. Special thanks also to all my beta testers and to Paolo Rosa, for their 
  28. encouragements and suggestions.
  29.  
  30.  
  31. PIP BASE FORMAT:
  32.  
  33. In this document I'll try to define Pip Message Base format.
  34.  
  35. I suggest you to get the MessageObject API (filerequest as MSGOBJ*.* from 
  36. Pip* support BBSes), and to take a look at header files and procedures (note 
  37. that this document is also included in MessageObject distribution package).
  38. I suppose that you're not novices in computer programming.
  39.  
  40. CONVENTIONS:
  41.  
  42. - all integers are 16 bits, in Intel format
  43. - long integers are 32 bits, Intel format
  44. - datas are aligned on bytes, unless otherwise specified
  45. - "uint" means "unsigned int"
  46.  
  47. BASICS:
  48.  
  49. - All Pip Base files reside in a single directory (except some configuration 
  50.   files that are generated and needed by specific programs); this directory 
  51.   will be referred to as the "message base directory"
  52.  
  53. - Every message area is contained into two files: a text file (MPKTxxxx.PIP)
  54.   and an index file (MPTRxxxx.PIP); xxxx is an hexadecimal integer, 
  55.   right-justified and zero-padded, indicating area number. Areas are numbered 
  56.   from 0 to 32767 (from M???0000.PIP to M???7FFF.PIP).
  57.  
  58. - To maintain smaller configuration and lasterad files, your system may limit 
  59.   the number of available areas. Pip* allows you to choose the area limit 
  60.   between 64, 256, 1024, 4096 and 32768 areas, and it will be a good idea to 
  61.   look at Pip* configuration files...
  62.  
  63. - An area description file, BASEDESC.PIP is stored in the same directory; all 
  64.   programs should refer to this file to configure themselves; the number of 
  65.   records in this file is the total number of areas in your systems; unused 
  66.   areas will have their respective record in BASEDESC.PIP zero-filled.
  67.  
  68. - An index file to rapidly find messages for a given user is called 
  69.   DESTPTR.PIP and is stored in the messagebase directory.
  70.  
  71. - A lastread pointers file, called LASTREAD.PIP and stored in the messagebase 
  72.   directory, contains lastread informations.
  73.  
  74. FILE STRUCTURE:
  75.  
  76. - MPTRxxxx.PIP: a file of records of type MSGPTR, indexing area xxxx.
  77.   record structure follows:
  78.   typedef struct /* structure of each record in MPTRxxxx.PIP files */
  79.                  { long pos;        /* pointer to MPKTxxxx.PIP */
  80.                    uint prev,next;  /* pointers to other records in MPTRxxxx */
  81.                    uint status;     /* bit 0=deleted 1=received 2=sent */
  82.                                     /* 3=fromus(1)/tous(0) */
  83.                                     /*4=Locked (Undeletable) */
  84.                  } MSGPTR;
  85.   pos points to the offset, in relative MPKTxxxx.PIP file, where the message 
  86.   header starts.
  87.  
  88. - MPKTxxxx.PIP: this file is composed by a serie of messages, follwed by two 
  89.   NUL bytes (the two NUL bytes are a sort of EOF identifier).
  90.   Each message is composed by:
  91.     - an header with the following structure:
  92.       typedef struct // structure of the message headers in MPKTxxxx.PIP files
  93.                { uint pktype; /* 2= not compressed; 10=compressed with PIP
  94.                  uint fromnode,tonode,fromnet,tonet; /* for netmail
  95.                  uint attribute; /* bit 0=private as for SeaDog,
  96.                                         1=crash as for SeaDog,
  97.                                         2=received as for SeaDog,
  98.                                         3=sent as for SeaDog,
  99.                                         4=fileattach as for SeaDog,
  100.                                         5=in transit as for SeaDog,
  101.                                         7=kill/sent as for SeaDog,
  102.                                         8=local as for SeaDog,
  103.                                         9=hold as for SeaDog,
  104.                                         10=locked,
  105.                                         11=filerequest as for SeaDog,
  106.                                         12=Return Receipt request,
  107.                                         13=Is Return Receipt,
  108.                                         14=Audit Request,
  109.                                         15=fileupdaterequest as for SeaDog */
  110.                  uint point; // reserved
  111.                } MSGPKTHDR;
  112.     - a nul-terminated string, 19 characters long (20, including the 
  113.       ending zero), containing the date of the message in the format
  114.       - day (two digits, right-justified and zero-padded)
  115.       - a space (ASCII decimal code 32)
  116.       - month (three letters: Jan/Feb/Mar/etc...)
  117.       - a space
  118.       - year (four digits, right-justified and zero-padded)
  119.       - two spaces
  120.       - hour (two digits, right-justified and zero-padded)
  121.       - a colon
  122.       - minute (two digits, right-justified and zero-padded)
  123.       - a colon
  124.       - seconds (two digits, right-justified and zero-padded)
  125.     - a nul-terminated string, of variable length (up to 35 characters long,
  126.       36 including trailing zero), containing the name of the recipient of the 
  127.       message
  128.     - a nul-terminated string, of variable length (up to 35 characters long,
  129.       36 including trailing zero), containing the name of the sender of the 
  130.       message
  131.     - a nul-terminated string, of variable length (up to 71 characters long,
  132.       72 including trailing zero), containing the name of the sender of the 
  133.       message
  134.     - a nul-terminated string, of variable length (theorically unbounded, but
  135.       every mailer may impose a specific limit, due to internal limitations; 
  136.       PipBase 1.00, my first mail processor, used a 30000 bytes limit; Pip* 
  137.       2.00 uses a length limited only by memory), containing message text.
  138.       - if the field pktype of the header was 2, the text is a regular, 
  139.         uncompressed, string
  140.       - if pktype was 10, the string is compressed using this fixed table:
  141.         Code          Meaning
  142.          0            Text terminator
  143.          1..127       regular ASCII characters
  144.          128          quote character: to represent non-7-bits characters 
  145.                       in two-bytes form: take the character that follows 
  146.                       the 128, add 127 and you'll obtain the character
  147.          129          "SEEN-BY: "
  148.          130          "MSGID: "
  149.          131          "PATH: "
  150.          132          ": "
  151.          133          "zion"
  152.          134          "ment"
  153.          135          "---"
  154.          136          "che"
  155.          137          "chi"
  156.          138          "ghe"
  157.          139          "ghi"
  158.          140          "str"
  159.          141          ""
  160.          142          "il"
  161.          143          "al"
  162.          144          "ed"
  163.          145          "pr"
  164.          146          "st"
  165.          147          ".."
  166.          148          "  "
  167.          149          ", "
  168.          150          ". "
  169.          151          "; "
  170.          152          "++"
  171.          153          "a'"
  172.          154          "e'"
  173.          155          "i'"
  174.          156          "o'"
  175.          157          "u'"
  176.          158          "a "
  177.          159          "e "
  178.          160          "i "
  179.          161          "o "
  180.          162          "u "
  181.          163          "nt"
  182.          164          "hi"
  183.          165          "bb"
  184.          166          "ba"
  185.          167          "be"
  186.          168          "bi"
  187.          169          "bo"
  188.          170          "bu"
  189.          171          "cc"
  190.          172          "ca"
  191.          173          "ce"
  192.          174          "ci"
  193.          175          "co"
  194.          176          "cu"
  195.          177          "dd"
  196.          178          "da"
  197.          179          "de"
  198.          180          "di"
  199.          181          "do"
  200.          182          "du"
  201.          183          "ff"
  202.          184          "fa"
  203.          185          "fe"
  204.          186          "fi"
  205.          187          "fo"
  206.          188          "fu"
  207.          189          "gg"
  208.          190          "ga"
  209.          191          "ge"
  210.          192          "gi"
  211.          193          "go"
  212.          194          "gu"
  213.          195          "ll"
  214.          196          "la"
  215.          197          "le"
  216.          198          "li"
  217.          199          "lo"
  218.          200          "lu"
  219.          201          "mm"
  220.          202          "ma"
  221.          203          "me"
  222.          204          "mi"
  223.          205          "mo"
  224.          206          "mu"
  225.          207          "nn"
  226.          208          "na"
  227.          209          "ne"
  228.          210          "ni"
  229.          211          "no"
  230.          212          "nu"
  231.          213          "pp"
  232.          214          "pa"
  233.          215          "pe"
  234.          216          "pi"
  235.          217          "po"
  236.          218          "pu"
  237.          219          "rr"
  238.          220          "ra"
  239.          221          "re"
  240.          222          "ri"
  241.          223          "ro"
  242.          224          "ru"
  243.          225          "ss"
  244.          226          "sa"
  245.          227          "se"
  246.          228          "si"
  247.          229          "so"
  248.          230          "su"
  249.          231          "tt"
  250.          232          "ta"
  251.          233          "te"
  252.          234          "ti"
  253.          235          "to"
  254.          236          "tu"
  255.          237          "vv"
  256.          238          "va"
  257.          239          "ve"
  258.          240          "vi"
  259.          241          "vo"
  260.          242          "vu"
  261.          243          "zz"
  262.          244          "za"
  263.          245          "ze"
  264.          246          "zi"
  265.          247          "zo"
  266.          248          "zu"
  267.          249          "=="
  268.          250          ":-"
  269.          251          "' "
  270.          252          "ha"
  271.          253          "ho"
  272.          254          "qu"
  273.          255          no meaning. Pip* translates it with a #
  274.         this compression method is not adaptive, but it works quite well on 
  275.         "normal" text (i.e.: text where you do not use high-ASCII characters 
  276.         and you do not SHOUT WITH ALL-CAPS PHRASES); adaptive algorithms can 
  277.         do better results in compression rates, but they're too slow to be 
  278.         used in a message reader.
  279.       - CRs (ASCII decimal code 13) are used to indicate <hard> CRs (i.e.: 
  280.         paragraph ends)
  281.       - ASCII code 141 is used to indicate a "soft CR", i.e.: where a line 
  282.         ends due to word-wrapping
  283.       - LFs (ASCII decimal code 10) are ignored
  284.       - kludges are, as usual, preceeded by an ASCII code 1
  285.  
  286. - DESTPTR.PIP: this file is composed by a sequence of records in the following
  287.   format:
  288.   typedef struct /* structure of each record in DESTPTR.PIP */
  289.                { char to[36]; /* addressee name */
  290.                  uint area,msg; /* pointers to MPTRarea.PIP records */
  291.                  long unused; /* reserved for future use */
  292.                } DESTPTR;
  293.  
  294. - BASEDESC.PIP: this file is a sequence of records (a record for each area; 
  295.   record number is the area number) of the following format:
  296.   typedef struct /* structure for each record of BASEDESC.PIP */
  297.                { char descr[40], /* description of the area */
  298.                       tag[30]; /* echomail tag, #LOCAL, #BAD,#DUPES or #NETMAIL */
  299.                  uint nrmsgs,days; /* to perform PURGE; nrmsgs=0: passthru area */
  300.                  unsigned char killrcv, /* kill received messages? */
  301.                       readlevel,readflags[4],writelevel,writeflags[4], /* for Remote Access style access control */
  302.                       origin, address, /* index for the appropriate table */
  303.                       note[80], /* whatever you want */
  304.                       forward_to[32]; /* this is a bitmap on FRIENDND.PIP's 256 records */
  305.                  char origmode; /* 0=fixed origin; 1=random system; 2=cyclic system */
  306.                  int startorig,endorig; /* for random or cyclic origin selection */
  307.                  long inmsgmonth,inmsgyear; /* for statistics */
  308.                  long outmsgmonth,outmsgyear; /* for statistics */
  309.                  char expansion_box[36]; /* please apply to define this */
  310.                } AREASTRUCT;
  311.  
  312. - LASTREAD.PIP: it is a large array of [number_of_users][number_of_areas] 
  313.   integers (message numbers); simply, lastread[user#][area#] is the last 
  314.   message read by the specified user. Usually, user#0 is the system operator.
  315.   Number_of_areas is the maximum number of areas that you allow in your 
  316.   system.
  317.  
  318. And that's all, folks.
  319. Send any suggestion, contribute, thanks, criticisms to:
  320. Roberto Piola
  321. 2:334/108.57@fidonet.org
  322.